'\" t
.\"     Title: IPSEC_KEYBLOBTOID
.\"    Author: Paul Wouters
.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
.\"      Date: 12/16/2012
.\"    Manual: Library functions
.\"    Source: libreswan
.\"  Language: English
.\"
.TH "IPSEC_KEYBLOBTOID" "3" "12/16/2012" "libreswan" "Library functions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec_keyblobtoid, ipsec_splitkeytoid \- generate key IDs from RSA keys
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <libreswan\&.h>

.fi
.ft
.HP \w'size_t\ keyblobtoid('u
.BI "size_t keyblobtoid(const\ unsigned\ char\ *\ " "blob" ", size_t\ " "bloblen" ", char\ *\ " "dst" ", size_t\ " "dstlen" ");"
.sp
.ft B
.nf

.fi
.ft
.HP \w'size_t\ splitkeytoid('u
.BI "size_t splitkeytoid(const\ unsigned\ char\ *\ " "e" ", size_t\ " "elen" ", const\ unsigned\ char\ *\ " "m" ", size_t\ " "mlen" ", char\ *\ " "dst" ", size_t\ " "dstlen" ");"
.SH "DESCRIPTION"
.PP
\fIKeyblobtoid\fR
and
\fBsplitkeytoid\fR
generate key IDs from RSA keys, for use in messages and reporting, writing the result to
\fIdst\fR\&. A
\fIkey ID\fR
is a short ASCII string identifying a key; currently it is just the first nine characters of the base64 encoding of the RFC 2537/3110 \(lqbyte blob\(rq representation of the key\&. (Beware that no finite key ID can be collision\-proof: there is always some small chance of two random keys having the same ID\&.)
.PP
\fIKeyblobtoid\fR
generates a key ID from a key which is already in the form of an RFC 2537/3110 binary key
\fIblob\fR
(encoded exponent length, exponent, modulus)\&.
.PP
\fISplitkeytoid\fR
generates a key ID from a key given in the form of a separate (binary) exponent
\fIe\fR
and modulus
\fIm\fR\&.
.PP
The
\fIdstlen\fR
parameter of either specifies the size of the
\fIdst\fR
parameter; under no circumstances are more than
\fIdstlen\fR
bytes written to
\fIdst\fR\&. A result which will not fit is truncated\&.
\fIDstlen\fR
can be zero, in which case
\fIdst\fR
need not be valid and no result is written, but the return value is unaffected; in all other cases, the (possibly truncated) result is NUL\-terminated\&. The
\fIlibreswan\&.h\fR
header file defines a constant
\fBKEYID_BUF\fR
which is the size of a buffer large enough for worst\-case results\&.
.PP
Both functions return
0
for a failure, and otherwise always return the size of buffer which would be needed to accommodate the full conversion result, including terminating NUL; it is the caller\*(Aqs responsibility to check this against the size of the provided buffer to determine whether truncation has occurred\&.
.PP
With keys generated by
\fBipsec_rsasigkey\fR(3), the first two base64 digits are always the same, and the third carries only about one bit of information\&. It\*(Aqs worse with keys using longer fixed exponents, e\&.g\&. the 24\-bit exponent that\*(Aqs common in X\&.509 certificates\&. However, being able to relate key IDs to the full base64 text form of keys by eye is sufficiently useful that this waste of space seems justifiable\&. The choice of nine digits is a compromise between bulk and probability of collision\&.
.SH "SEE ALSO"
.PP
RFC 3110,
\fIRSA/SHA\-1 SIGs and RSA KEYs in the Domain Name System (DNS)\fR, Eastlake, 2001 (superseding the older but better\-known RFC 2537)\&.
.SH "DIAGNOSTICS"
.PP
Fatal errors are: key too short to supply enough bits to construct a complete key ID (almost certainly indicating a garbage key); exponent too long for its length to be representable\&.
.SH "HISTORY"
.PP
Written for the FreeS/WAN project by Henry Spencer\&.
.SH "AUTHOR"
.PP
\fBPaul Wouters\fR
.RS 4
placeholder to suppress warning
.RE
